ποΈGitΠ―ΡΠ°ποΈ
docs/payloads.md 890a2e2cffa98dea3ca88db3c3aba72ef23ff3f7 (890a2e2c) Text, 14.92 KB
Payload Format
Inside each MeshCore Packet is a payload, identified by the payload type in the packet header. The types of payloads are:
β’ Node advertisement.
β’ Acknowledgment.
β’ Returned path.
β’ Request (destination/source hashes + MAC).
β’ Response to REQ or ANON_REQ.
β’ Plain text message.
β’ Anonymous request.
β’ Group text message (unverified).
β’ Group datagram (unverified).
β’ Multi-part packet
β’ Control data packet
β’ Custom packet (raw bytes, custom encryption).
This document defines the structure of each of these payload types.
NOTE: all 16 and 32-bit integer fields are Little Endian.
Important concepts:
β’ Node hash: the first byte of the node's public key
Node advertisement
This kind of payload notifies receivers that a node exists, and gives information about the node
ββββββββββββββ¬ββββββββββββββββββ¬βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β Field β Size (bytes) β Description β
ββββββββββββββΌββββββββββββββββββΌβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β public key β 32 β Ed25519 public key of the node β
β timestamp β 4 β unix timestamp of advertisement β
β signature β 64 β Ed25519 signature of public key, timestamp, and app data β
β appdata β rest of payload β optional, see below β
ββββββββββββββ΄ββββββββββββββββββ΄βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
Appdata
βββββββββββββ¬ββββββββββββββββββ¬βββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β Field β Size (bytes) β Description β
βββββββββββββΌββββββββββββββββββΌβββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β flags β 1 β specifies which of the fields are present, see below β
β latitude β 4 (optional) β decimal latitude multiplied by 1000000, integer β
β longitude β 4 (optional) β decimal longitude multiplied by 1000000, integer β
β feature 1 β 2 (optional) β reserved for future use β
β feature 2 β 2 (optional) β reserved for future use β
β name β rest of appdata β name of the node β
βββββββββββββ΄ββββββββββββββββββ΄βββββββββββββββββββββββββββββββββββββββββββββββββββββββ
Appdata Flags
βββββββββ¬βββββββββββββββββ¬ββββββββββββββββββββββββββββββββββββββββ
β Value β Name β Description β
βββββββββΌβββββββββββββββββΌββββββββββββββββββββββββββββββββββββββββ€
β T3838380x01 β is chat node β advert is for a chat node β
β T3838380x02 β is repeater β advert is for a repeater β
β T3838380x03 β is room server β advert is for a room server β
β T3838380x04 β is sensor β advert is for a sensor server β
β T3838380x10 β has location β appdata contains lat/long information β
β T3838380x20 β has feature 1 β Reserved for future use. β
β T3838380x40 β has feature 2 β Reserved for future use. β
β T3838380x80 β has name β appdata contains a node name β
βββββββββ΄βββββββββββββββββ΄ββββββββββββββββββββββββββββββββββββββββ
Acknowledgement
An acknowledgement that a message was received. Note that for returned path messages, an acknowledgement can be sent in the "extra" payload (see Returned Path) instead of as a separate acknowledgement packet. CLI commands do not cause acknowledgement responses, neither discrete nor extra.
ββββββββββββ¬βββββββββββββββ¬βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β Field β Size (bytes) β Description β
ββββββββββββΌβββββββββββββββΌβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β checksum β 4 β CRC checksum of message timestamp, text, and sender pubkey β
ββββββββββββ΄βββββββββββββββ΄βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
Returned path, request, response, and plain text message
Returned path, request, response, and plain text messages are all formatted in the same way. See the subsection for more details about the ciphertext's associated plaintext representation.
ββββββββββββββββββββ¬ββββββββββββββββββ¬βββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β Field β Size (bytes) β Description β
ββββββββββββββββββββΌββββββββββββββββββΌβββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β destination hash β 1 β first byte of destination node public key β
β source hash β 1 β first byte of source node public key β
β cipher MAC β 2 β MAC for encrypted data in next field β
β ciphertext β rest of payload β encrypted message, see subsections below for details β
ββββββββββββββββββββ΄ββββββββββββββββββ΄βββββββββββββββββββββββββββββββββββββββββββββββββββββββ
Returned path
Returned path messages provide a description of the route a packet took from the original author. Receivers will send returned path messages to the author of the original message.
βββββββββββββββ¬βββββββββββββββ¬ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β Field β Size (bytes) β Description β
βββββββββββββββΌβββββββββββββββΌββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β path length β 1 β length of next field β
β path β see above β a list of node hashes (one byte each) β
β extra type β 1 β extra, bundled payload type, eg., acknowledgement or response. Samβ¦ β
β extra β rest of data β extra, bundled payload content, follows same format as main contenβ¦ β
βββββββββββββββ΄βββββββββββββββ΄ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
Request
ββββββββββββββββ¬ββββββββββββββββββ¬βββββββββββββββββββββββββββββββββββββββββββ
β Field β Size (bytes) β Description β
ββββββββββββββββΌββββββββββββββββββΌβββββββββββββββββββββββββββββββββββββββββββ€
β timestamp β 4 β sender time (unix timestamp) β
β request data β rest of payload β application-defined request payload body β
ββββββββββββββββ΄ββββββββββββββββββ΄βββββββββββββββββββββββββββββββββββββββββββ
For the common chat/server helpers in T383838BaseChatMesh, the current request type values are:
βββββββββ¬ββββββββββββ¬βββββββββββββββββββββββββββββββββββββββββββββββββββββ
β Value β Name β Description β
βββββββββΌββββββββββββΌβββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β T3838380x01 β get stats β get stats of repeater or room server β
β T3838380x02 β keepalive β keep-alive request used for maintained connections β
βββββββββ΄ββββββββββββ΄βββββββββββββββββββββββββββββββββββββββββββββββββββββ
Get stats
Gets information about the node, possibly including the following:
β’ Battery level (millivolts)
β’ Current transmit queue length
β’ Current free queue length
β’ Last RSSI value
β’ Number of received packets
β’ Number of sent packets
β’ Total airtime (seconds)
β’ Total uptime (seconds)
β’ Number of packets sent as flood
β’ Number of packets sent directly
β’ Number of packets received as flood
β’ Number of packets received directly
β’ Error flags
β’ Last SNR value
β’ Number of direct route duplicates
β’ Number of flood route duplicates
β’ Number posted (?)
β’ Number of post pushes (?)
Get telemetry data
Not defined in T383838BaseChatMesh. Sensor- and application-specific request payloads may be implemented by higher-level firmware.
Get Telemetry
Not defined in T383838BaseChatMesh.
Get Min/Max/Ave (Sensor nodes)
Not defined in T383838BaseChatMesh.
Get Access List
Not defined in T383838BaseChatMesh.
Get Neighbors
Not defined in T383838BaseChatMesh.
Get Owner Info
Not defined in T383838BaseChatMesh.
Response
βββββββββββ¬ββββββββββββββββββ¬ββββββββββββββββββββββββββββββββββββ
β Field β Size (bytes) β Description β
βββββββββββΌββββββββββββββββββΌββββββββββββββββββββββββββββββββββββ€
β content β rest of payload β application-defined response body β
βββββββββββ΄ββββββββββββββββββ΄ββββββββββββββββββββββββββββββββββββ
Response contents are opaque application data. There is no single generic response envelope beyond the encrypted payload wrapper shown above.
Plain text message
ββββββββββββββββββββββ¬ββββββββββββββββββ¬ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β Field β Size (bytes) β Description β
ββββββββββββββββββββββΌββββββββββββββββββΌββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β timestamp β 4 β send time (unix timestamp) β
β txt_type + attempt β 1 β upper six bits are txt_type (see below), lower two bits β¦ β
β message β rest of payload β the message content, see next table β
ββββββββββββββββββββββ΄ββββββββββββββββββ΄ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
txt_type
βββββββββ¬ββββββββββββββββββββββββββββ¬βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β Value β Description β Message content β
βββββββββΌββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β T3838380x00 β plain text message β the plain text of the message β
β T3838380x01 β CLI command β the command text of the message β
β T3838380x02 β signed plain text message β first four bytes is sender pubkey prefix, followed by plainβ¦ β
βββββββββ΄ββββββββββββββββββββββββββββ΄βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
Anonymous request
ββββββββββββββββββββ¬ββββββββββββββββββ¬ββββββββββββββββββββββββββββββββββββββββββββ
β Field β Size (bytes) β Description β
ββββββββββββββββββββΌββββββββββββββββββΌββββββββββββββββββββββββββββββββββββββββββββ€
β destination hash β 1 β first byte of destination node public key β
β public key β 32 β sender's Ed25519 public key β
β cipher MAC β 2 β MAC for encrypted data in next field β
β ciphertext β rest of payload β encrypted message, see below for details β
ββββββββββββββββββββ΄ββββββββββββββββββ΄ββββββββββββββββββββββββββββββββββββββββββββ
Room server login
ββββββββββββββββββ¬ββββββββββββββββββ¬βββββββββββββββββββββββββββββββββββββββββββββ
β Field β Size (bytes) β Description β
ββββββββββββββββββΌββββββββββββββββββΌβββββββββββββββββββββββββββββββββββββββββββββ€
β timestamp β 4 β sender time (unix timestamp) β
β sync timestamp β 4 β sender's "sync messages SINCE x" timestamp β
β password β rest of message β password for room β
ββββββββββββββββββ΄ββββββββββββββββββ΄βββββββββββββββββββββββββββββββββββββββββββββ
Repeater/Sensor login
βββββββββββββ¬ββββββββββββββββββ¬βββββββββββββββββββββββββββββββ
β Field β Size (bytes) β Description β
βββββββββββββΌββββββββββββββββββΌβββββββββββββββββββββββββββββββ€
β timestamp β 4 β sender time (unix timestamp) β
β password β rest of message β password for repeater/sensor β
βββββββββββββ΄ββββββββββββββββββ΄βββββββββββββββββββββββββββββββ
Repeater - Regions request
ββββββββββββββββββ¬βββββββββββββββ¬βββββββββββββββββββββββββββββββ
β Field β Size (bytes) β Description β
ββββββββββββββββββΌβββββββββββββββΌβββββββββββββββββββββββββββββββ€
β timestamp β 4 β sender time (unix timestamp) β
β req type β 1 β 0x01 (request sub type) β
β reply path len β 1 β path len for reply β
β reply path β (variable) β reply path β
ββββββββββββββββββ΄βββββββββββββββ΄βββββββββββββββββββββββββββββββ
Repeater - Owner info request
ββββββββββββββββββ¬βββββββββββββββ¬βββββββββββββββββββββββββββββββ
β Field β Size (bytes) β Description β
ββββββββββββββββββΌβββββββββββββββΌβββββββββββββββββββββββββββββββ€
β timestamp β 4 β sender time (unix timestamp) β
β req type β 1 β 0x02 (request sub type) β
β reply path len β 1 β path len for reply β
β reply path β (variable) β reply path β
ββββββββββββββββββ΄βββββββββββββββ΄βββββββββββββββββββββββββββββββ
Repeater - Clock and status request
ββββββββββββββββββ¬βββββββββββββββ¬βββββββββββββββββββββββββββββββ
β Field β Size (bytes) β Description β
ββββββββββββββββββΌβββββββββββββββΌβββββββββββββββββββββββββββββββ€
β timestamp β 4 β sender time (unix timestamp) β
β req type β 1 β 0x03 (request sub type) β
β reply path len β 1 β path len for reply β
β reply path β (variable) β reply path β
ββββββββββββββββββ΄βββββββββββββββ΄βββββββββββββββββββββββββββββββ
Group text message
ββββββββββββββββ¬ββββββββββββββββββ¬βββββββββββββββββββββββββββββββββββββββββββββββ
β Field β Size (bytes) β Description β
ββββββββββββββββΌββββββββββββββββββΌβββββββββββββββββββββββββββββββββββββββββββββββ€
β channel hash β 1 β first byte of SHA256 of channel's shared key β
β cipher MAC β 2 β MAC for encrypted data in next field β
β ciphertext β rest of payload β encrypted message, see below for details β
ββββββββββββββββ΄ββββββββββββββββββ΄βββββββββββββββββββββββββββββββββββββββββββββββ
The plaintext contained in the ciphertext matches the format described in plain text message. Specifically, it consists of a four byte timestamp, a flags byte, and the message. The flags byte will generally be T3838380x00 because it is a "plain text message". The message will be of the form T383838<sender name>: <message body> (eg., T383838user123: I'm on my way).
The sender name is unverified message text. Group messages contain no sender
signature, so any channel-key holder can choose any sender name.
Group datagram
ββββββββββββββββ¬ββββββββββββββββββ¬βββββββββββββββββββββββββββββββββββββββββββββββ
β Field β Size (bytes) β Description β
ββββββββββββββββΌββββββββββββββββββΌβββββββββββββββββββββββββββββββββββββββββββββββ€
β channel hash β 1 β first byte of SHA256 of channel's shared key β
β cipher MAC β 2 β MAC for encrypted data in next field β
β ciphertext β rest of payload β encrypted data, see below for details β
ββββββββββββββββ΄ββββββββββββββββββ΄βββββββββββββββββββββββββββββββββββββββββββββββ
The data contained in the ciphertext uses the format below:
βββββββββββββ¬ββββββββββββββββββ¬βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β Field β Size (bytes) β Description β
βββββββββββββΌββββββββββββββββββΌβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β data type β 2 β Identifier for type of data. (See number_allocations.md) β
β data len β 1 β byte length of data β
β data β rest of payload β (depends on data type) β
βββββββββββββ΄ββββββββββββββββββ΄βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
Control data
βββββββββ¬ββββββββββββββββββ¬βββββββββββββββββββββββββββββ
β Field β Size (bytes) β Description β
βββββββββΌββββββββββββββββββΌβββββββββββββββββββββββββββββ€
β flags β 1 β upper 4 bits is sub_type β
β data β rest of payload β typically unencrypted data β
βββββββββ΄ββββββββββββββββββ΄βββββββββββββββββββββββββββββ
DISCOVERREQ (subtype)
βββββββββββββββ¬βββββββββββββββ¬βββββββββββββββββββββββββββββββββββββββββββββββ
β Field β Size (bytes) β Description β
βββββββββββββββΌβββββββββββββββΌβββββββββββββββββββββββββββββββββββββββββββββββ€
β flags β 1 β 0x8 (upper 4 bits), prefix_only (lowest bit) β
β type_filter β 1 β bit for each ADVTYPE* β
β tag β 4 β randomly generate by sender β
β since β 4 β (optional) epoch timestamp (0 by default) β
βββββββββββββββ΄βββββββββββββββ΄βββββββββββββββββββββββββββββββββββββββββββββββ
DISCOVERRESP (subtype)
ββββββββββ¬βββββββββββββββ¬ββββββββββββββββββββββββββββββββββββββββββ
β Field β Size (bytes) β Description β
ββββββββββΌβββββββββββββββΌββββββββββββββββββββββββββββββββββββββββββ€
β flags β 1 β 0x9 (upper 4 bits), node_type (lower 4) β
β snr β 1 β signed, SNR*4 β
β tag β 4 β reflected back from DISCOVER_REQ β
β pubkey β 8 or 32 β node's ID (or prefix) β
ββββββββββ΄βββββββββββββββ΄ββββββββββββββββββββββββββββββββββββββββββ
Custom packet
Custom packets have no defined format.
Served by rngit 1.5.2 - Generated in 0.1s